Wes/core architecture rework - #2638
Conversation
…in their frontmatter are hidden from the nav and return 404 when accessed directly unless VITE_SHOW_DRAFTS=true is set. In preview mode, draft nav items render in warning amber and draft pages show a callout banner.
|
Here's a visual recap of what changed: Open the full interactive recap
|
steve8708
left a comment
There was a problem hiding this comment.
great stuff wes - may have some localized mdx we need to update/move too
oxfmt --check was failing on this extra blank line.
Adds five new draft MDX pages (server-overview, server-database, server-middleware, server-plugins, server-routes) and an Agents placeholder, wired into the nav under a draft Server group. Pages are hidden in production and visible with VITE_SHOW_DRAFTS=true. Includes nav keys in all locale files and an updated i18n doc-coverage baseline to exempt draft pages from the localized-doc requirement.
Reframes db.ts as optional rather than default, moves the database plugin section after auth and agent-chat, expands the intro to explain what plugins are and how Nitro discovers them, and adds a new section on writing custom plugins with defineNitroPlugin linking to Nitro docs.
…are guide Expands the draft from a stub into a full page: - Adds a diagram showing callers → middleware → allowed/blocked outcomes - Rewrites the intro to describe middleware as a general cross-cutting layer - Adds a "Writing Middleware" section with a defineEventHandler example and links to Nitro/H3 docs, placed before the auth section - Consolidates The Auth Guard, Why Middleware, and Adding Public Paths under a single "The Auth Middleware" H2 with those as H3 subheadings
…agram Reorganizes the draft from a loosely ordered reference into a narrative that builds from concept to implementation: - New diagram showing Browser/UI and Agent loop reaching the database through the same Actions layer - Hosting Options section covering all five backends in order of complexity (SQLite default, PGlite, Postgres, Turso, Builder managed) - Setting Up section as four numbered steps: define schema, create DB client, write migrations, query in actions - Scoping Data to Users consolidates the owner_email and ownableColumns patterns that were previously scattered - Removes all em-dashes throughout in favor of separate sentences
Ports the sync loop content from the published server.mdx into the database page, where it completes the write story: after an action mutates data, the sync version increments and useDbSync() on the client invalidates caches so the UI refreshes. Includes the sync loop diagram and the poll endpoint block. Adds a What's next link to real-time-sync.
Splits server.mdx into five pages (overview, database, middleware, plugins, routes), un-drafts them in the nav, and repoints cross-page links across the docs that pointed at the old combined page.
Translates the 5 server-*.mdx docs (overview, database, middleware, plugins, routes) into ar-SA, de-DE, es-ES, fr-FR, hi-IN, ja-JP, ko-KR, pt-BR, zh-CN, and zh-TW, replacing verbatim English copies left over from the Server section split. - Remove the old single-page server.mdx from every locale; it has no English source counterpart since the split and was unreachable. - Translate the Server dropdown's sidebar labels (Overview, Middleware, Plugins, Routes, and Server itself for ar-SA/hi-IN) so the nav structure matches across locales. - Fix a stale content/server.md reference in docs/AGENTS.md. - Drop 50 now-stale entries from the doc-coverage baseline and add "Agent Native" to the no-translate-terms allowlist so the guard no longer flags the brand name as an untranslated string.
- Point the Real-Time Sync link at the existing key-concepts#polling-sync anchor instead of the non-existent /docs/real-time-sync slug. - server-database.mdx copied its diagram/AnnotatedCode/DataModel blocks from database.mdx without regenerating their ids, so three blocks collided with database.mdx's own blocks of the same id. Assign each a unique id. Applies to the English source and all 10 locale translations, which mirrored the same bugs.
a95bb67 to
ea56af6
Compare
- Add a /docs/server -> /docs/server-overview redirect (both the default
and localized slug routes) now that server.mdx is split into five pages.
- Teach stable migration names in server-database.mdx and
server-plugins.mdx: version-only migrations collide across branches that
reuse the same version number, which runMigrations' name-based tracking
is designed to avoid.
- Correct server-plugins.mdx's startup-order section: default plugins load
in lexical order (agent-chat.ts, auth.ts, db.ts), and Nitro does not await
one plugin's async init before starting the next.
- Add explicit {#id} anchors to headings that relied on the ASCII-only
heading slugger, which produced empty/duplicate anchors for non-Latin
translations.
…-rework # Conflicts: # packages/core/docs/content/agent-surfaces.mdx # packages/docs/app/routes/docs.$locale.$slug.tsx # packages/docs/app/routes/docs.$slug.tsx # scripts/i18n-localized-doc-coverage-baseline.txt
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Builder reviewed your changes and has a few items to flag 🟡
Review Details
Incremental Review Summary
The latest commit adds the localized versions of the split Server documentation and addresses two findings from the previous review: the duplicate block identifiers were changed to unique IDs, and both default and localized docs routes now redirect the legacy server slug to server-overview. Those fixes were verified and the corresponding review threads were resolved.
No new actionable findings were returned by the incremental review workers before the session was interrupted. Previously reported issues that remain open were not resubmitted: the missing /docs/real-time-sync target, the unsafe timingSafeEqual example, the SQLite-incompatible migration example, and the Agent Surfaces link whose target does not document the promised production handler signature. The newly added locale files are structurally aligned with the English split and the navigation now has localized page sources.
Risk assessment: Low risk — documentation, navigation, and localization changes only. 🧪 Browser testing: Will run after this review (PR touches docs UI/navigation code).
The new Server section .mdx files weren't run through oxfmt before commit.

This PR breaks the Server page up into several different pages. The previous Server page has several different concepts within it, while this attempts to break it up into more manageable chunks that are a bit more readable and understandable. A general overview is below:
This does not yet include translations. I want to get this reviewed for content before spending the tokens on translations. :)